Skip Headers

Oracle® C++ Call Interface Programmer's Guide 10g Release 2 (10.2) Part Number B14294-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# Date C lass

The Date class specifies the abstraction for a SQL `DATE` data item. The Date class also adds formatting and parsing operations to support the OCCI escape syntax for date values.

Since SQL92 DATE is a subset of Oracle Date, this class can be used to support both.

Objects from the Date class can be used as standalone class objects in client side numerical computations and also used to fetch from, and set to, the database.

Example 12-5 How to Get a Date from Database and Use it in Standalone Calculations

This example demonstrates a Date column value being retrieved from the database, a bind using a Date object, and a computation using a standalone Date object.

    /* Create a connection */
    Environment *env = Environment::createEnvironment(Environment::DEFAULT);
    Connection *conn = env->createConnection(user, passwd, db);

    /* Create a statement and associate a DML statement to it */
    string sqlStmt = "SELECT job-id, start_date from JOB_HISTORY
                                where end_date = :x";
    Statement *stmt = conn->createStatement(sqlStmt);

    /* Create a Date object and bind it to the statement */
    Date edate(env, 2000, 9, 3, 23, 30, 30);
    stmt->setDate(1, edate);
    ResultSet *rset = stmt->executeQuery();

    /* Fetch a date from the database */
    while(rset->next())
    {
       Date sd = rset->getDate(2);
       Date temp = sd;    /*assignment operator */
       /* Methods on Date */
       temp.getDate(year, month, day, hour, minute, second);
       temp.setMonths(2);
       IntervalDS inter = temp.daysBetween(sd);
       .
       .
    }

Table 12-16 Summary of Date Methods

Method | Summary
--- | ---
Date() | `Date` class constructor.
addDays() | Returns a `Date` object with n days added.
addMonths() | Returns a `Date` object with n months added.
daysBetween() | Returns the number of days between the current `Date` object and the date specified.
fromBytes() | Convert an external `Bytes` representation of a `Date` object to a `Date` object.
fromText() | Convert the date from a given input string with format and nls parameters specified.
getDate()() | Returns the date and time components of the `Date` object.
getSystemDate() | Returns a `Date` object containing the system date.
isNull() | Returns `TRUE` if `Date` is `NULL``; otherwise returns` `false`.
lastDay() | Returns a `Date` that is the last day of the month.
nextDay() | Returns a `Date` that is the date of the next day of the week.
operator=() | Assigns the values of a date to another.
operator==() | Returns `TRUE` if `a` and `b` are the same, `false` otherwise.
operator!=() | Returns `TRUE` if `a` and `b` are unequal, `false` otherwise.
operator>() | Returns `TRUE` if `a` is past `b`, `false` otherwise.
operator>=() | Returns `TRUE` if `a` is past `b or equal to b`, `false` otherwise.
operator=() | Returns `TRUE` if `a` is before `b`, `false` otherwise.
operator>() | Returns `TRUE` if `a` is before `b`, or equal to b, `false` otherwise.
setDate() | Sets the date from the date components input.
setNull() | Sets the object state to `NULL`.
toBytes() | Converts the `Date` object into an external `Bytes` representation.
toText() | Returns the `Date` object as a string.
toZone() | Returns a `Date` object converted from one time zone to another.

## Date()

`Date` class constructor.

Syntax | Description
--- | ---
    Date();
| Creates a `NULL` `Date` object.
    Date(
       const Date &srcDate);
| Creates a copy of a `Date` object.
    Date(
       const Environment *envp,
       int year = 1,
       unsigned int month = 1,
       unsigned int day = 1,
       unsigned int hour = 0,
       unsigned int minute = 0,
       unsigned int seconds = 0);
| Creates a `Date` object using integer parameters.

Parameter | Description
--- | ---
year | -4712 to 9999, except 0
month | 1 to 12
day | 1 to 31
minutes | 0 to 59
seconds | 0 to 59

## addDays()

Adds a specified number of days to the `Date` object and returns the new date.

Syntax

    Date addDays(
       int val) const;

Parameter | Description
--- | ---
    val
| The number of days to be added to the current `Date` object.

## addMonths()

Adds a specified number of months to the `Date` object and returns the new date.

Syntax

    Date addMonths(
       int val) const;

Parameter | Description
--- | ---
    val
| The number of months to be added to the current `Date` object.

## daysBetween()

Returns the number of days between the current `Date` object and `the date specified`.

Syntax

    IntervalDS daysBetween(
       const Date &date) const;

Parameter | Description
--- | ---
    date
| The date to be used to compute the days between.

## fromBytes()

Converts a `Bytes` object to a `Date` object.

Syntax

    void fromBytes(
       const Bytes &byteStream,
       const Environment *envp = NULL);

Parameter | Description
--- | ---
    byteStream
| `Date` in external format in the form of Bytes.
    envp
| The OCCI environment.

## fromText()

Sets `Date` object to value represented by a `string` or `UString`.

The value is interpreted based on the `fmt` and `nlsParam` parameters. In cases where `nlsParam` is not passed, the Globalization Support settings of the `envp` parameter are used.

See Also: Oracle Database SQL Reference for information on `TO_DATE`

Syntax | Description
--- | ---
    void fromText(
       const string &datestr,
       const string &fmt = "",
       const string &nlsParam = "",
       const Environment *envp = NULL);
| Sets `Date` object to value represented by a `string`.
    void fromText(
       const UString &datestr,
       const UString &fmt,
       const UString &nlsParam,
       const Environment *envp = NULL);
| Sets `Date` object to value represented by a `UString`; globalization enabled.

Parameter | Description
--- | ---
    envp
| The OCCI environment.
    datestr
| The date string to be converted to a `Date` object.
    fmt
| The format string; default is `DD-MON-YY`.
    nlsParam
| The nls parameters string. If `nlsParam` is specified, this determines the nls parameters to be used for the conversion. If `nlsParam` is not specified, the nls parameters are picked up from `envp`.

## getDate()

Returns the date in the form of the date components year, month, day, hour, minute, seconds.

Syntax

    void getDate(
       int &year,
       unsigned int &month,
       unsigned int &day,
       unsigned int &hour,
       unsigned int &min,
       unsigned int &seconds) const;

Parameter | Description
--- | ---
    year
| The year component of the date.
    month
| The month component of the date.
    day
| The day component of the date.
    hour
| The hour component of the date.
    min
| The minutes component of the date.
    seconds
| The seconds component of the date.

## getSystemDate()

Returns the system date.

Syntax

    static Date getSystemDate(
       const Environment *envp);

Parameter | Description
--- | ---
    envp
| The environment in which the system date is returned.

## isNull()

Tests whether the `Date` is `NULL`. If the `Date` is `NULL`, `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool isNull() const;

## lastDay()

Returns a date representing the last day of the current month.

Syntax

    Date lastDay() const;

## nextDay()

Returns a date representing the day after the day of the week specified.

See Also: Oracle Database SQL Reference for information on `TO_DATE`

Syntax | Description
--- | ---
    Date nextDay(
       const string &dow) const;
| Returns a date representing the day after the day of the week specified.
    Date nextDay(
       const UString &dow) const;
| Returns a date representing the day after the day of the week specified.; globalization enabled. The parameter should be in the character set associated with the environment from which the date was created.

Parameter | Description
--- | ---
    dow
| A string representing the day of the week.

## operator=()

Assigns the date object on the right side of the equal (=) sign to the date object on the left side of the equal (=) sign.

Syntax

    Date& operator=(
       const Date &d);

Parameter | Description
--- | ---
    date
| The date object that is assigned.

## operator==()

Compares the dates specified. If the dates are equal, `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool operator==(
       const Date &first,
       const Date &second);

Parameter | Description
--- | ---
    first
| The first date to be compared.
    second
| The second date to be compared.

## operator!=()

Compares the dates specified. If the dates are not equal then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool operator!=(
       const Date &first,
       const Date &second);

Parameter | Description
--- | ---
    first
| The first date to be compared.
    second
| The second date to be compared.

## operator>()

Compares the dates specified. If the first date is in the future relative to the second date then `TRUE` is returned; otherwise, `FALSE` is returned. If either date is `NULL` then `FALSE` is returned. If `the dates are` not the same type then `FALSE` is returned.

Syntax

    bool operator>(
       const Date &first,
       const Date &second);

Parameter | Description
--- | ---
    first
| The first date to be compared.
    second
| The second date to be compared.

## operator>=()

Compares the dates specified. If the first date is in the future relative to the second date or the dates are equal then `TRUE` is returned; otherwise, `FALSE` is returned. If either date is `NULL` then `FALSE` is returned. `If the dates are not the same type then FALSE is returned.`

Syntax

    bool operator>=(
       const Date &first,
       const Date &second);

Parameter | Description
--- | ---
    first
| The first date to be compared.
    second
| The second date to be compared.

## operator<()

Compares the dates specified. If the first date is in the past relative to the second date then `TRUE` is returned; otherwise, `FALSE` is returned. If either date is `NULL` then `FALSE` is returned. If the dates are not the same type then `FALSE` is returned.

Syntax

    bool operator<(
       const Date &first,
       const Date &second);

Parameter | Description
--- | ---
    first
| The first date to be compared.
    second
| The second date to be compared.

## operator<=()

Compares the dates specified. If the first date is in the past relative to the second date or the dates are equal then `TRUE` is returned; otherwise, `FALSE` is returned. If either date is `NULL` then `FALSE` is returned. If the dates are not the same type then `FALSE` is returned.

Syntax

    bool operator<=(
       const Date &first,
       const Date &second);

Parameter | Description
--- | ---
    first
| The first date to be compared.
    second
| The second date to be compared.

## setDate()

Sets the date to the values specified.

Syntax

    void setDate(
       int year = 1,
       unsigned int month = 1,
       unsigned int day = 1,
       unsigned int hour = 0,
       unsigned int minute = 0,
       unsigned int seconds = 0);

Parameter | Description
--- | ---
    year
| The argument specifying the year value. Valid values are `-4713` through `9999`.
    month
| The argument specifying the month value. Valid values are `1` through `12`.
    day
| The argument specifying the day value. Valid values are 1 through 31.
    hour
| The argument specifying the hour value. Valid values are 0 through 23.
    min
| The argument specifying the minutes value. Valid values are 0 through 59.
    seconds
| The argument specifying the seconds value. Valid values are 0 through 59.

## setNull()

Sets the `Date` to atomically `NULL`.

Syntax

    void setNull();

## toBytes()

Returns the date in `Bytes` representation.

Syntax

    Bytes toBytes() const;

## toText()

Returns a `string` or `UString` with the value of this date formatted using `fmt` and `nlsParam`.

The value is interpreted based on the `fmt` and `nlsParam` parameters. In cases where `nlsParam` is not passed, the Globalization Support settings of the `envp` parameter are used.

See Also: Oracle Database SQL Reference for information on `TO_DATE`

Syntax | Description
--- | ---
    string toText(
       const string &fmt = "",
       const string &nlsParam = "") const;
| Returns a `string` with the value of this date formatted using `fmt` and `nlsParam`.
    UString toText(
       const UString &fmt,
       const UString &nlsParam) const;
| Returns a `UString` with the value of this date formatted using `fmt` and `nlsParam`.

Parameter | Description
--- | ---
    fmt
| The format string; default is `DD-MON-YY`.
    nlsParam
| The nls parameters string. If `nlsParam` is specified, this determines the nls parameters to be used for the conversion. If `nlsParam` is not specified, the nls parameters are picked up from `envp`.

## toZone()

Returns `Date` value converted from one time zone to another.

Syntax

    Date toZone(
       const string &zone1,
       const string &zone2) const;

Parameter | Description
--- | ---
    zone1
| A string representing the time zone to be converted from.
    zone2
| A string representing the time zone to be converted to.

Valid time zone codes are:

Zone code | Value
--- | ---
`AST, ADT` | Atlantic Standard or Daylight Time
`BST, BDT` | Bering Standard or Daylight Time
`CST, CDT` | Central Standard or Daylight Time
`EST, EDT` | Eastern Standard or Daylight Time
`GMT` | Greenwich Mean Time
`HST, HDT` | Alaska-Hawaii Standard Time or Daylight Time
`MST, MDT` | Mountain Standard or Daylight Time
`NST` | Newfoundland Standard Time
`PST, PDT` | Pacific Standard or Daylight Time
`YST, YDT` | Yukon Standard or Daylight Time